Get Tool Agent Count

Used to retrieve the number of AI agents currently using a specific tool. This provides insights into tool adoption and usage across your project.

API Endpoint

Property	Value
Request Method	GET
Request URL	https://api.seliseblocks.com/tools/{tool_id}/agent-count

Request

Request Example

curl -X GET 'https://api.seliseblocks.com/tools/{tool_id}/agent-count?project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

Path Parameters

Field	Type	Required	Description
tool_id	string	Yes	The unique identifier of the tool.

Query Parameters

Field	Type	Required	Description
project_key	string	No	The project key for your project.

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json

note

Agent Count Information

• Counts only active AI agents that have the tool configured
• Includes agents in all statuses (active, inactive, testing)
• Updated in real-time as agents are added or removed
• Useful for understanding tool adoption and dependencies

tip

Use cases for agent count:

• Monitoring tool adoption across your organization
• Identifying popular and underutilized tools
• Assessing impact before making changes to a tool
• Planning tool deprecation or migration
• Understanding dependencies before deletion
• Tracking tool usage growth over time

This information helps you:

• Make informed decisions about tool maintenance
• Prioritize support and improvements for widely-used tools
• Identify tools that can be safely deprecated
• Plan capacity and resource allocation
• Communicate changes to affected teams

Response

Success Response (200 OK)

Returns the count of agents using the tool.

{
  "success": true,
  "message": "Agent count retrieved successfully",
  "data": 12,
  "status_code": 200
}

Response Fields

Field	Type	Description
success	boolean	Indicates whether the request was successful.
message	string	Human-readable status message.
data	integer	Number of AI agents using this tool.
status_code	integer	HTTP status code (200 for success).

Zero Agents Response

Returns when no agents are using the tool.

{
  "success": true,
  "message": "No agents currently using this tool",
  "data": 0,
  "status_code": 200
}

note

A count of 0 indicates that:

• The tool is not currently configured in any AI agents
• The tool is new and hasn't been adopted yet
• The tool may be a candidate for deprecation
• It's safe to delete the tool without affecting active agents

Error Response (422 Unprocessable Entity)

Returns validation error details when the request parameters are invalid.

{
  "detail": [
    {
      "loc": [
        "path",
        "tool_id"
      ],
      "msg": "tool not found",
      "type": "value_error.notfound"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., path, query).
msg	string	Human-readable error message.
type	string	Error type identifier.

Interpreting Agent Count

Agent Count	Interpretation	Recommended Actions
0	Tool is not being used	Safe to delete; consider deprecation
1-5	Low adoption	Investigate reasons; promote usage or deprecate
6-20	Moderate adoption	Monitor usage; plan carefully before changes
21-50	High adoption	Critical tool; changes require careful planning
50+	Very high adoption	Mission-critical; coordinate changes widely

Error Codes

Status Code	Description	Response Type
200	Successful Response	Success
400	Bad Request - Invalid request	Bad Request
404	Not Found - Tool does not exist	Not Found
422	Validation Error - Invalid request parameters	Unprocessable Entity